/**
 *     This file is part of cesm-ws.
 *
 *     cesm-ws, Web Service for Community Earth System Model
 *
 *     Copyright (c) 2010, Purdue University and/or affilicates or thrid-party contributors as
 *     indicated by the @author tags or express copyright attribution statements
 *     applied by the authors. All third-party contributions are distributed under
 *     license by Purdue University.
 *
 *     cesm-ws is free software: you can redistribute it and/or modify
 *     it under the terms of the GNU General Public License as published by
 *     the Free Software Foundation, either version 3 of the License, or
 *     (at your option) any later version.
 *
 *     This program is distributed in the hope that it will be useful,
 *     but WITHOUT ANY WARRANTY; without even the implied warranty of
 *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *     GNU General Public License for more details.
 *
 *     You should have received a copy of the GNU Lesser General Public License
 *     along with this distribution.  If not, see <http://www.gnu.org/licenses/>.
 */

package edu.purdue.rcac.cesm.ws.soap;

import java.util.List;

import javax.activation.DataHandler;

import edu.purdue.rcac.cesm.define.DirectoryAlias;
import edu.purdue.rcac.cesm.facade.bean.AllCaseInfoBean;
import edu.purdue.rcac.cesm.facade.bean.AllCaseNameBean;
import edu.purdue.rcac.cesm.facade.bean.AllJobInfoBean;
import edu.purdue.rcac.cesm.facade.bean.CaseConfigFileBean;
import edu.purdue.rcac.cesm.facade.bean.CaseConfigInfoBean;
import edu.purdue.rcac.cesm.facade.bean.CaseRuntimeInfoBean;
import edu.purdue.rcac.cesm.facade.bean.ConfigVarBean;
import edu.purdue.rcac.cesm.facade.bean.ConfigVarListBean;
import edu.purdue.rcac.cesm.facade.bean.CreateCaseBean;
import edu.purdue.rcac.cesm.facade.bean.DownloadBean;
import edu.purdue.rcac.cesm.facade.bean.FileBean;
import edu.purdue.rcac.cesm.facade.bean.KeyValueEntry;

/**
 * CCSM4 web service SOAP interface definition
 * 
 * @author Han Zhang
 */
public interface CESMSOAPInterface {
	/**
	 * Create a new CCSM test case
	 */
	public CreateCaseBean createCase(String resolution, String componentSet,
			String allocation, String machine, String caseName,
			String userName, String password) throws CESMSOAPFault;

	/**
	 * Get the current value of a configuration variable
	 */
	public ConfigVarBean queryConfigVar(String varName, String userName,
			String caseName, String token) throws CESMSOAPFault;

	/**
	 * Set the value of a configuration variable
	 */
	public String setConfigVar(String varName, String varValue,
			String userName, String caseName, String token)
			throws CESMSOAPFault;

	/**
	 * Configure a case
	 */
	public String configureCase(String userName, String caseName, String token)
			throws CESMSOAPFault;

	/**
	 * Reset configuration
	 */
	public String resetConfig(String userName, String caseName, String token)
			throws CESMSOAPFault;

	/**
	 * Build and Run a CCSM case
	 * 
	 * @param userName
	 * @param caseName
	 * @param email
	 * @param queueToRun
	 * @param wallTime
	 *            Wall time for PBS job, formated as
	 *            [hour:[minute:[second.[millisecond]]] or just integer of
	 *            seconds<br>
	 *            e.g. 2:00:00 is similar as 7200
	 * @param token
	 * @return {@link RunCaseBean} instance
	 * @throws CESMSOAPFault
	 */
	public String runCase(String userName, String caseName, String email,
			String queueToRun, String wallTime, String token)
			throws CESMSOAPFault;

	/**
	 * Show all the cases owned by a user
	 */
	public AllCaseNameBean listAllCaseName(String userName, String token)
			throws CESMSOAPFault;

	/**
	 * Cancel a case which is either in queue or running
	 */
	public String cancelCase(String userName, String caseName, String token)
			throws CESMSOAPFault;

	/**
	 * Delete all the data related to a case from the system
	 */
	public String deleteCase(String userName, String caseName, String token)
			throws CESMSOAPFault;

	/**
	 * Query the status of a case
	 */
	public String getJobStatus(String userName, String caseName, String token)
			throws CESMSOAPFault;

	/**
	 * Query the walltime usage
	 */
	public String getUsedWallTime(String userName, String caseName, String token)
			throws CESMSOAPFault;

	/**
	 * Query the CPU usage
	 */
	public String getUsedCPUTime(String userName, String caseName, String token)
			throws CESMSOAPFault;

	/**
	 * Return output file location for download (http/ftp?)
	 */
	public String getOutputLocation(String userName, String caseName,
			String token) throws CESMSOAPFault;

	/**
	 * Return "true" if token is valid, otherwise return "false"
	 */
	public boolean isTokenValid(String username, String token)
			throws CESMSOAPFault;

	/**
	 * return pbs.out content
	 */
	public String getPbsOut(String username, String casename, String token)
			throws CESMSOAPFault;

	/**
	 * Return pbs.err content
	 */
	public String getPbsErr(String username, String casename, String token)
			throws CESMSOAPFault;

	/**
	 * Invoke "qstat -a -u ccsmuser" in the backend
	 */
	public AllJobInfoBean listAllJobInfo(String username, String queueName,
			String machine, String token) throws CESMSOAPFault;

	/**
	 * Get case related information
	 */
	public CaseConfigInfoBean getCaseConfigInfo(String username,
			String caseName, String token) throws CESMSOAPFault;

	public CaseRuntimeInfoBean getCaseRuntimeInfo(String username,
			String caseName, String token) throws CESMSOAPFault;

	public AllCaseInfoBean listAllCaseInfo(String userName, String token)
			throws CESMSOAPFault;

	/**
	 * Return a token if user is authenticated, otherwise return ""
	 */
	public String authenticate(String username, String password)
			throws CESMSOAPFault;

	public String createUserHome(String userName, String token)
			throws CESMSOAPFault;

	/**
	 * List all the configuration variables that can be changed
	 */
	public ConfigVarListBean getConfigVarList(String userName, String caseName,
			String token) throws CESMSOAPFault;

	public String setConfigVarList(String userName, String caseName,
			List<KeyValueEntry> varList, String token) throws CESMSOAPFault;

	// UPLOAD & DOWNLOAD
	public String upload(String userName,DirectoryAlias targetDir, String toPath,
			DataHandler data, String token) throws CESMSOAPFault;

	public DownloadBean download(String userName, DirectoryAlias targetDir, String path, String token)
			throws CESMSOAPFault;

	// FTP-like OPERATION
	public List<FileBean> list(String userName, String path,
			DirectoryAlias basedir, String token) throws CESMSOAPFault;

	public String mkdir(String userName, String path, DirectoryAlias basedir,
			String token) throws CESMSOAPFault;

	public String remove(String userName, String path, DirectoryAlias basedir,
			String token) throws CESMSOAPFault;

	public String move(String userName, String fromPath, String toPath,
			DirectoryAlias basedir, String token) throws CESMSOAPFault;

	public String rename(String userName, String fromPath, String toPath,
			DirectoryAlias basedir, String token) throws CESMSOAPFault;

	// PUBLISH OPERATION - operations to publish data to ESG
	public String publish(String userName, String caseName, String token)
			throws CESMSOAPFault;

	public String unpublish(String userName, String caseName, String token)
			throws CESMSOAPFault;

	public String getPublishStatus(String userName, String caseName,
			String token) throws CESMSOAPFault;
}
